You may have seen our recent announcement about SocketBox, a new WebSocket functionality built into CommandBox’s latest 6.1-rc builds and the latest snapshots of the BoxLang MiniServer. Take a moment to read that post first if you haven’t heard about SocketBox yet.
SocketBox provides you with basic WebSocket connection management and low level messaging to build upon. And, as of today, we’ve also added a STOMP broker as an option for you to use. STOMP stands for Simple Text Oriented Messaging Protocol and provides additional semantics on top of basic WebSockets for
- Message format/serialization
- Authentication/Authorization
- Topics and message routing
- Subscriptions to a topic
- Sending messages to a destination
- Automatic client reconnect
- Heartbeat messages to detect dead connections
To use STOMP WebSocket support, you’ll use a WebSocket.cfc in your web root again, but now you’ll want to extend the modules.socketbox.models.WebSocketSTOMP class. This class provides all the same functionality as the WebSocketCore class, but with much more.
It adds the following methods you can override in your custom WebSocket.cfc.
configure()- You can configure the STOMP broker via a struct returned from this method (see below)authenticate( required string login, required string passcode, string host, required channel )- Allows custom authentication logic to accept or deny a STOMP connect request. Note a STOMP connect message is different from a low level WebSocket connection.authorize( required string login, required string exchange, required string destination, required string access, required channel )- Allows custom authorization logic to allow or deny a client from being able to subscribe to a destination or publish to a destination.
With STOMP, messages can be sent from a WebSocket connection using a Stomp.js library OR from the server side like so:
new WebSocket().send( 'my-destination', "my message" );
Furthermore, messages can be received by client side JS code in the browser or via a server-side listener using CF code.
function configure() {
return {
"subscriptions" : {
"ping" : (message)=>{
// Reply by sending a message to the pong destination
send(
"pong-destination",
"Ping Pong!"
);
},
"generate-new-sales-data" : (message)=>{
salesService.generate();
send(
"sales-data-updated",
"New sales data available as of #now()#"
);
}
}
};
}
STOMP also has a powerful routing system based on the idea of exchanges. You don’t send messages directly to subscriptions. You send messages to an exchange, which decides how and where to route the message. This means a single message could be routed to zero or many recipient destinations.
Here are the exchange types and their config.
direct- Routes message directly to the destination matching their destination header.bindings- configure custom bindings between a destination and another destination.
topic- Routes messages to destinations via wildcard subscriptions allowing partial match semantics on destinations namedfoo.bar.baz.bindings- Configure destinations using*and#as wildcards to match a single segment or many segments respectively
fanout- Routes message to ALL bindings at the same timebindings- Matches each incoming destination to an array of outgoing destinations
distribution- Routes messages to a SINGLE outgoing destination based on a selection algorithmtype- The valuerandomorroundrobin.bindings- Same as fanout, but only one destination will be chosen at a time
Furthermore, STOMP has plumbing to both
- authenticate client connection requests (based on user/pass, session variables, or even JWT)
- authorize whether a given connection has permissions to subscribe to or publish to a given exchange and destination key.
This allows you to have a fully-secure app.
This is just a few of the many things you can do with STOMP. Read the full documentation here:
And finally, we’ve published another full demo, which is deployed to the free tier of Render.com and running on the BoxLang Miniserver Docker container. The demo should also run on Lucee and Adobe CF as well, so long as they are deployed on the latest CommandBox 6.1-rc builds and have WebSockets enabled in the server.json.
Live Demo Here:
https://socketbox-stomp-demo.onrender.com/
The source code for the demo is also available here and fully documented to walk you through what it’s doing: